<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<link rel="shortcut icon" type="image/x-icon" href="favicon.ico"/>
<title>DynamoRIO API: dr_app.h File Reference</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
</script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
  $(document).ready(function() { searchBox.OnSelectItem(0); });
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td style="padding-left: 0.5em;">
   <div id="projectname">DynamoRIO API
   </div>
  </td>
   <td>        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <img id="MSearchSelect" src="search/mag_sel.png"
               onmouseover="return searchBox.OnSearchSelectShow()"
               onmouseout="return searchBox.OnSearchSelectHide()"
               alt=""/>
          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
          </span>
        </div>
</td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.1.1 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('dr__app_8h.html','');});
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark">&#160;</span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark">&#160;</span>Data Structures</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark">&#160;</span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark">&#160;</span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark">&#160;</span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark">&#160;</span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark">&#160;</span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark">&#160;</span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark">&#160;</span>Macros</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(9)"><span class="SelectionMark">&#160;</span>Groups</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(10)"><span class="SelectionMark">&#160;</span>Pages</a></div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="summary">
<a href="#func-members">Functions</a>  </div>
  <div class="headertitle">
<div class="title">dr_app.h File Reference</div>  </div>
</div><!--header-->
<div class="contents">

<p>DR's application interface for running portions of a program under its control.  
<a href="#details">More...</a></p>
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2><a name="func-members"></a>
Functions</h2></td></tr>
<tr class="memitem:abcdedd068a4d264401c31767355ec218"><td class="memItemLeft" align="right" valign="top">DR_APP_API int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="dr__app_8h.html#abcdedd068a4d264401c31767355ec218">dr_app_setup</a> (void)</td></tr>
<tr class="memitem:a216ee7d3e25b4c31edf5a9b2ba93d533"><td class="memItemLeft" align="right" valign="top">DR_APP_API int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="dr__app_8h.html#a216ee7d3e25b4c31edf5a9b2ba93d533">dr_app_cleanup</a> (void)</td></tr>
<tr class="memitem:afb7b7aed03dd6f0ed8d48b8a8796e55e"><td class="memItemLeft" align="right" valign="top">DR_APP_API void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="dr__app_8h.html#afb7b7aed03dd6f0ed8d48b8a8796e55e">dr_app_start</a> (void)</td></tr>
<tr class="memitem:afd509bb9ea5d1947228de48dda256e8f"><td class="memItemLeft" align="right" valign="top">DR_APP_API void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="dr__app_8h.html#afd509bb9ea5d1947228de48dda256e8f">dr_app_stop</a> (void)</td></tr>
<tr class="memitem:a43dead944cb3c75de2537404b568f8ec"><td class="memItemLeft" align="right" valign="top">DR_APP_API void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="dr__app_8h.html#a43dead944cb3c75de2537404b568f8ec">dr_app_take_over</a> (void)</td></tr>
<tr class="memitem:ace92a2658a46bb5811ece68ae964fd62"><td class="memItemLeft" align="right" valign="top">DR_APP_API int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="dr__app_8h.html#ace92a2658a46bb5811ece68ae964fd62">dr_app_setup_and_start</a> (void)</td></tr>
<tr class="memitem:aea917a6c24c8bf526f77772b0b9848a8"><td class="memItemLeft" align="right" valign="top">DR_APP_API bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="dr__app_8h.html#aea917a6c24c8bf526f77772b0b9848a8">dr_app_running_under_dynamorio</a> (void)</td></tr>
<tr class="memitem:aba46eea03a20e5801b87b7cd54d26bf5"><td class="memItemLeft" align="right" valign="top">DR_APP_API void *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="dr__app_8h.html#aba46eea03a20e5801b87b7cd54d26bf5">dr_app_handle_mbr_target</a> (void *target)</td></tr>
</table>
<hr/><a name="details" id="details"></a><h2>Detailed Description</h2>
<div class="textblock"><p>DR's application interface for running portions of a program under its control. </p>
</div><hr/><h2>Function Documentation</h2>
<a class="anchor" id="a216ee7d3e25b4c31edf5a9b2ba93d533"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">DR_APP_API int dr_app_cleanup </td>
          <td>(</td>
          <td class="paramtype">void&#160;</td>
          <td class="paramname"></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Application-wide cleanup. Prints statistics. Returns zero on success. </p>

</div>
</div>
<a class="anchor" id="aba46eea03a20e5801b87b7cd54d26bf5"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">DR_APP_API void* dr_app_handle_mbr_target </td>
          <td>(</td>
          <td class="paramtype">void *&#160;</td>
          <td class="paramname"><em>target</em></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>DynamoRIO's (experimental) native execution mode supports running some modules natively while the others run under DynamoRIO. When a module is running natively, it may jump to a module that should be executed under DynamoRIO directly without going through DynamoRIO. To handle this situation, the application code should call this routine and use the returned stub pc as the branch target instead. </p>
<dl class="section note"><dt>Note:</dt><dd>Linux only. </dd>
<dd>
Native execution mode only. </dd>
<dd>
Experimental support. </dd></dl>

</div>
</div>
<a class="anchor" id="aea917a6c24c8bf526f77772b0b9848a8"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">DR_APP_API bool dr_app_running_under_dynamorio </td>
          <td>(</td>
          <td class="paramtype">void&#160;</td>
          <td class="paramname"></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Indicates whether the current thread is running within the DynamoRIO code cache. Returns <code>true</code> only if the current thread is running within the DynamoRIO code cache and returns false othrewise.</p>
<dl class="section note"><dt>Note:</dt><dd>This routines returns <code>false</code> if the current thread is running within the DynamoRIO probe mode. </dd></dl>

</div>
</div>
<a class="anchor" id="abcdedd068a4d264401c31767355ec218"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">DR_APP_API int dr_app_setup </td>
          <td>(</td>
          <td class="paramtype">void&#160;</td>
          <td class="paramname"></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Application-wide initialization. Must be called before any other API function. Returns zero on success. </p>

</div>
</div>
<a class="anchor" id="ace92a2658a46bb5811ece68ae964fd62"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">DR_APP_API int dr_app_setup_and_start </td>
          <td>(</td>
          <td class="paramtype">void&#160;</td>
          <td class="paramname"></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Calls <a class="el" href="dr__app_8h.html#abcdedd068a4d264401c31767355ec218">dr_app_setup()</a> and, if it succeeds, calls <a class="el" href="dr__app_8h.html#afb7b7aed03dd6f0ed8d48b8a8796e55e">dr_app_start()</a>. Returns the result of <a class="el" href="dr__app_8h.html#abcdedd068a4d264401c31767355ec218">dr_app_setup()</a>, which returns zero on success. This routine is intended as a convenient single point of entry for callers who are using dlsym() or GetProcAddress() to access the app API. </p>

</div>
</div>
<a class="anchor" id="afb7b7aed03dd6f0ed8d48b8a8796e55e"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">DR_APP_API void dr_app_start </td>
          <td>(</td>
          <td class="paramtype">void&#160;</td>
          <td class="paramname"></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Causes application to run under DR control upon return from this call. Attempts to take over any existing threads in the application.</p>
<dl class="section warning"><dt>Warning:</dt><dd>On Linux, DR detects threads by listing thread ids in the current process's thread group. This, and other queries about the current process may fail if the main thread has quit. DR also assumes the threads all share signal handlers, as is the case for pthreads. Violating these assumptions will lead to unpredictable behavior.</dd>
<dd>
Windows does not yet attempt to take over existing threads. </dd></dl>

</div>
</div>
<a class="anchor" id="afd509bb9ea5d1947228de48dda256e8f"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">DR_APP_API void dr_app_stop </td>
          <td>(</td>
          <td class="paramtype">void&#160;</td>
          <td class="paramname"></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Causes the application's current thread to run directly on the machine upon return from this call; no effect if application is not currently running under DR control.</p>
<dl class="section note"><dt>Note:</dt><dd>This only affects the current thread. Other threads will still be under DR's control. This behavior may change in the future. </dd></dl>

</div>
</div>
<a class="anchor" id="a43dead944cb3c75de2537404b568f8ec"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">DR_APP_API void dr_app_take_over </td>
          <td>(</td>
          <td class="paramtype">void&#160;</td>
          <td class="paramname"></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Causes application to run under DR control upon return from this call. DR never releases control. Useful for overriding dr_app_start/dr_app_stop calls in the rest of a program. </p>

</div>
</div>
</div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="navelem"><a class="el" href="dir_3f960cec7fb648840e8ab2c814e874ae.html">include</a></li><li class="navelem"><a class="el" href="dr__app_8h.html">dr_app.h</a></li>
    <li class="footer" style="float:none;text-align:center"><img border=0 src="favicon.png"> &nbsp;  DynamoRIO API version 5.0.0 --- Wed Sep 10 2014 21:36:43 &nbsp; <img border=0 src="favicon.png">
</small></address>
<!--END !GENERATE_TREEVIEW-->
</body>
</html>
